Help/Extending and Customizing SC/Helper/Helper.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.44">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; color: #0000ff}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; min-height: 12.0px}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 12.0px Helvetica; min-height: 14.0px}
  18 p.p9 {margin: 0.0px 0.0px 0.0px 85.0px; text-indent: -85.0px; font: 12.0px Helvetica}
  19 p.p10 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco}
  20 p.p11 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 14.0px Helvetica}
  21 p.p12 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #753927}
  22 p.p13 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  23 p.p14 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #6d3c2a}
  24 p.p15 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #1e39a3}
  25 p.p16 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #6d3c2a}
  26 p.p17 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #1e39a3}
  27 p.p18 {margin: 0.0px 0.0px 0.0px 57.0px; text-indent: -57.0px; font: 9.0px Monaco; color: #606060}
  28 span.s1 {font: 18.0px Helvetica}
  29 span.s2 {color: #000000}
  30 span.s3 {text-decoration: underline}
  31 span.s4 {color: #233da4}
  32 span.s5 {color: #1e39a3}
  33 span.Apple-tab-span {white-space:pre}
  34 </style>
  35 </head>
  36 <body>
  37 <p class="p1"><span class="s1"><b>Helper<span class="Apple-tab-span">   </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></b></span><b>documentation template autogeneration</b><span class="s1"><b><span class="Apple-tab-span"> </span></b></span></p>
  38 <p class="p2"><br></p>
  39 <p class="p1"><b>Inherits from: Object</b></p>
  40 <p class="p3"><br></p>
  41 <p class="p1">Helper allows to autogenerate a documentation template for classes, ugens, topics.</p>
  42 <p class="p1">The resulting file strictly follows the provided templates styles, so that you have to worry only about content and not about formatting.<span class="Apple-converted-space"> </span></p>
  43 <p class="p1">Note that for consistency you should always use this class while creating help files.<span class="Apple-converted-space"> </span></p>
  44 <p class="p2"><br></p>
  45 <p class="p4"><span class="s2"><b>See also:</b> <a href="../Style Guide/Documentation Style Guide.html"><span class="s3">Documentation Style Guide</span></a></span></p>
  46 <p class="p2"><br></p>
  47 <p class="p5"><b>Helper structure</b></p>
  48 <p class="p2"><br></p>
  49 <p class="p1">Helper class works by inspecting the argument passed to the constructor. It then calls three other<span class="Apple-converted-space">  </span>classes specialized for classes, ugens and topics (<b>ClassHelper</b>, <b>UGenHelper</b>, <b>TopicHelper</b>).<span class="Apple-converted-space">  </span>TopicHelper is selected if you pass a string (i.e. the topic you want to discuss).</p>
  50 <p class="p1">Each of them is given a makeHelp method which generates the help file template. In case of classes, this is done by analysing the source code and retrieving vars, methods, arguments, default values. If you have "private" methods, or other things you think that should not be documented, you have to delete their description from the help file.</p>
  51 <p class="p1">Note that not only you do not have to deal with this structure but more typically you simply pass the item to the makeHelp method of Help class (see Examples below).</p>
  52 <p class="p2"><br></p>
  53 <p class="p1">Please note that:<span class="Apple-converted-space"> </span></p>
  54 <p class="p1">- if you want to overwrite an existing help file you have to delete it or rename it before using Helper;<span class="Apple-converted-space"> </span></p>
  55 <p class="p1">- in order to reopen automatically the created file for editing, the path must be in one of the SC recognized paths.</p>
  56 <p class="p1">- in order to reopen automatically the created file for editing, the name must be the one of the class to be documented.</p>
  57 <p class="p1">Please note also that in all the previous cases<span class="Apple-converted-space">  </span>the requested file is created.</p>
  58 <p class="p2"><br></p>
  59 <p class="p5"><b>Creation / Class Methods</b></p>
  60 <p class="p6"><br></p>
  61 <p class="p7"><b><span class="Apple-tab-span">  </span>*new (undocumentedObject, path)</b></p>
  62 <p class="p8"><b><span class="Apple-tab-span">  </span></b></p>
  63 <p class="p7"><b><span class="Apple-tab-span">  </span><span class="Apple-tab-span">    </span></b>Write the helpfile by selecting the specialized class. Then it tries to reopen the generated help file</p>
  64 <p class="p9"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><b>undocumentedObject </b>- the item you want to document. Default value is nil. The method select the opportune specialized Class, and sends to its instance the makeHelp message.</p>
  65 <p class="p9"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span> <b>path </b>- the path where to write the help file. Default value is nil: in that case you are prompted to select a path by a dialog. After creation SC tries to reopen the file by calling undocumentedObject.openHelpFile. See Examples for requirements.</p>
  66 <p class="p8"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span></p>
  67 <p class="p10"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>// of course we can document better this class</p>
  68 <p class="p10"><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>h = <span class="s4">Helper</span>.new(<span class="s5">Helper</span>);<span class="Apple-converted-space"> </span></p>
  69 <p class="p6"><br></p>
  70 <p class="p11"><b>Examples</b></p>
  71 <p class="p3"><br></p>
  72 <p class="p12">//////////</p>
  73 <p class="p12">// CLASSES</p>
  74 <p class="p12">//////////</p>
  75 <p class="p3"><br></p>
  76 <p class="p13"><span class="s5">Helper</span>(<span class="s5">TestClass2</span>, "/Users/andreavalle/Library/Application\ Support/SuperCollider/Extensions/Help/mine/TestClass2.html")</p>
  77 <p class="p14">// TestClass2: a test class</p>
  78 <p class="p15">Helper(TestClass2)</p>
  79 <p class="p14">// prompts for path (must be complete).</p>
  80 <p class="p3"><br></p>
  81 <p class="p13"><span class="s5">Helper</span>(<span class="s5">TestClass2</span>, "/test/TestClass2.html")</p>
  82 <p class="p14">// this works but then it can't open the resulting help file</p>
  83 <p class="p14">// in order to reopen it automatically, the provided path</p>
  84 <p class="p12">// must be one of the recognized ones</p>
  85 <p class="p3"><br></p>
  86 <p class="p12">//////////</p>
  87 <p class="p12">// UGENS</p>
  88 <p class="p12">//////////</p>
  89 <p class="p3"><br></p>
  90 <p class="p13"><span class="s5">Helper</span>(<span class="s5">SinOsc</span>, "/Users/andreavalle/Library/Application\ Support/SuperCollider/Extensions/Help/mine/SinOsc.html")</p>
  91 <p class="p15">Helper(SinOsc)</p>
  92 <p class="p14">// In this case SinOsc has already a help file, so Helper opens that one </p>
  93 <p class="p14">// as it calls SinOsc.openHelpFile</p>
  94 <p class="p3"><br></p>
  95 <p class="p12">//////////</p>
  96 <p class="p12">// TOPICS</p>
  97 <p class="p12">//////////</p>
  98 <p class="p3"><br></p>
  99 <p class="p13"><span class="s5">Helper</span>("On_Helper", "/Users/andreavalle/Library/Application\ Support/SuperCollider/Extensions/Help/mine/On_Helper.html")</p>
 100 <p class="p13"><span class="s5">Helper</span>("On_Helper")</p>
 101 <p class="p14">// it's a bit boring to repeat the class or the topic name with html as a path</p>
 102 <p class="p14">// but I don't see a way to propose to GUI save dialog a fileName, so in that case you would have</p>
 103 <p class="p14">// to specify it the same. </p>
 104 <p class="p14">// Document was indeed more flexible</p>
 105 <p class="p6"><br></p>
 106 <p class="p14">// instead of direct instantiantion<span class="Apple-converted-space"> </span></p>
 107 <p class="p14">// you may typically use makeHelp<span class="Apple-converted-space">  </span>method on the Help class:</p>
 108 <p class="p14">// Help.makeHelp wraps the Helper class for you</p>
 109 <p class="p3"><br></p>
 110 <p class="p12">// TYPICAL USAGE with Help extension</p>
 111 <p class="p14">// The same as before</p>
 112 <p class="p16">// an undocumented class</p>
 113 <p class="p17">Help.makeHelp(ClassHelper);<span class="Apple-converted-space"> </span></p>
 114 <p class="p16">// an undocumented topic</p>
 115 <p class="p18"><span class="s5">Help</span>.makeHelp("On the Helper class");<span class="Apple-converted-space"> </span></p>
 116 <p class="p16">// an undocumented UGen</p>
 117 <p class="p17">Help.makeHelp(HilbertFIR);<span class="Apple-converted-space"> </span></p>
 118 <p class="p3"><br></p>
 119 <p class="p3"><br></p>
 120 </body>
 121 </html>